@Part[MISC, Root = "CLM.MSS"]
@Comment{Chapter of Common Lisp Manual.  Copyright 1984 Guy L. Steele Jr.⎇


@MyChapter[Miscellaneous Features]

In this chapter are described various things that don't
seem to fit neatly anywhere else in this book:
the compiler, the @f[documentation]
function, debugging aids, environment inquiries (including facilities
for calculating and measuring time), and the @f[identity] function.

@Section[The Compiler]

The compiler is a program that may make code run faster by translating
programs into an implementation-dependent form that can
be executed more efficiently by the computer.  Most of the time
you can write programs without worrying about the compiler;
compiling a file of code should produce an equivalent but more
efficient program.  When doing more esoteric things, you may need to
think carefully about what happens at ``compile time'' and what happens
at ``load time.''  Then the difference between the syntaxes @f[#.]
and @f[#,] becomes important, and the @Specref[eval-when] construct
becomes particularly useful.

Most declarations are not used by the @clisp interpreter;
they may be used to give advice to the compiler.  The compiler may attempt
to check your advice and warn you if it is inconsistent.

Unlike most other @xlisp dialects, @clisp recognizes @f[special]
declarations in interpreted code as well as compiled code.
This potential source of incompatibility between interpreted and compiled
code is thereby @i[eliminated] in @clisp.

The internal workings of a compiler will of course be highly
implementation-dependent.  The following functions provide a standard
interface to the compiler, however.


@Defun[Fun {compile⎇, Args {@i[name] @optional @i[definition]⎇]
If @i[definition] is supplied, it should be a lambda-expression,
the interpreted function to be compiled.  If it is not supplied,
then @i[name] should be a symbol with a definition that is a
lambda-expression; that definition is compiled
and the resulting compiled code is put back into the symbol
as its function definition.

The definition is compiled and a compiled-function object produced.
If @i[name] is a non-@nil
symbol, then the compiled-function object is installed as the
global function definition of the symbol and the symbol is returned.
If @i[name] is @false, then the compiled-function object itself is returned.
For example:
@lisp
@Tabset[40]
(defun foo ...) @EV foo@\;@r[A function definition.]
(compile 'foo) @EV foo@\;@r[Compile it.]
	;@r[Now @f[foo] runs faster.]
(compile @false '(lambda (a b c) (- (* b b) (* 4 a c))))
   @EV @r[a compiled function of three arguments that computes @i[b]@+[2]@Minussign@;4@i[ac]]
@Endlisp
@Enddefun

@Defun[Fun {compile-file⎇, Args {@i[input-pathname]⎇, Keys {[output-file]⎇]
The @i[input-pathname] must be a valid file specifier, such as a pathname.
The defaults for @i[input-filename] are taken from the variable
@Varref[default-pathname-defaults].
The file should be a @xlisp source file;
its contents are compiled and written as a binary object file.

The @Kwd[output-file] argument may be used to specify an output pathname;
it defaults in a manner
appropriate to the implementation's file system conventions.
@Enddefun

@Defun[Fun {disassemble⎇, Args {@i[name-or-compiled-function]⎇]
The argument should be either a function object, a lambda-expression, or
a symbol with a function definition.  If the relevant function is not a
compiled function, it is first compiled.  In any case, the compiled code
is then ``reverse-assembled'' and printed out in a symbolic format.  This
is primarily useful for debugging the compiler, but also often of use to
the novice who wishes to understand the workings of compiled code.
@Implementation{Implementors are encouraged to make the output
readable, preferably with helpful comments.⎇
@Enddefun

@Section[Documentation]

A simple facility is provided for attaching strings to
symbols for the purpose of on-line documentation.
Rather than using the property list of the symbol,
a separate function @f[documentation] is provided
so that implementations can optimize the storage of
documentation strings.

@Defun[Fun {documentation⎇, Args {@i[symbol] @i[doc-type]⎇]
This function returns the documentation string of type @i[doc-type]
for the @i[symbol], or @false if none exists.  Both arguments must be symbols.
Some kinds of documentation are provided automatically by certain
@clisp constructs if the user writes an optional documentation string within
them:
@Begin[Format]
@tabset[+2.2in]
@ux[Construct@\Documentation Type]
@Macref[defvar]@\@f[variable]
@Macref[defparameter]@\@f[variable]
@Macref[defconstant]@\@f[variable]
@Macref[defun]@\@f[function]
@Macref[defmacro]@\@f[function]
@Macref[defstruct]@\@f[structure]
@Macref[deftype]@\@f[type]
@Macref[defsetf]@\@f[setf]
@End[Format]
In addition, names of special forms may also have @f[function] documentation.
(Macros and special forms are not really functions, of course, but it is
convenient to group them with functions for documentation purposes.)

@Macref[setf] may be used with @f[documentation] to update
documentation information.
@Enddefun

@Section[Debugging Tools]

The utilities described in this section are sufficiently complex
and sufficiently dependent on the host environment that their
complete definition is beyond the scope of this manual.
However, they are also sufficiently
useful as to warrant mention here.  It is expected
every implementation will
provide some version of these utilities, however clever or however simple.

@Defmac[Fun {trace⎇, Args {@Mstar<@i[function-name]>⎇]
@Defmac1[Fun {untrace⎇, Args {@Mstar<@i[function-name]>⎇]
Invoking @f[trace] with one or more function names (symbols) causes
the functions named to be traced.  Henceforth, whenever such
a function is invoked, information about the call, the arguments
passed, and the eventually returned values, if any, will be printed
to the stream that is the value of @Varref[trace-output].
For example:
@lisp
(trace fft gcd chase-pacman)
@Endlisp
If a function call is open-coded (possibly as a result of an @f[inline]
declaration), then such a call may not produce trace output.

Invoking @f[untrace] with one or more function names will cause those
functions not to be traced any more.

Tracing an already traced function, or untracing a function not
currently being traced, should produce no harmful effects, but may
produce a warning message.

Calling @f[trace] with no argument forms will return a list of functions
currently being traced.

Calling @f[untrace] with no argument forms will cause all currently
traced functions to be no longer traced.

@f[trace] and @f[untrace] may also accept additional
implementation-dependent argument formats.  The format of the trace
output is implementation-dependent.
@Enddefmac


@Defmac[Fun {step⎇, Args {@i[form]⎇]
This evaluates @i[form] and returns what @i[form] returns.
However, the user is allowed to interactively
``single-step'' through the evaluation of @i[form], at least
through those evaluation steps that are performed interpretively.
The nature of the interaction is implementation-dependent.
However, implementations are encouraged to respond to the typing
of the character @f[?] by providing help including a list
of commands.
@Enddefmac

@Defmac[Fun {time⎇, Args {@i[form]⎇]
This evaluates @i[form] and returns what @i[form] returns.  However, as
a side effect, various timing data and other information are printed to
the stream that is the value of @Varref[trace-output].  The nature and
format of the printed information is implementation-dependent.  However,
implementations are encouraged to provide such information as elapsed
real time, machine run time, storage management statistics, and so on.
@Incompatibility{This facility is inspired by the @interlisp
facility of the same name.  Note that the @maclisp/@lmlisp function @f[time]
does something else entirely, namely return a quantity indicating
relative elapsed real time.⎇
@Enddefmac

@Defun[Fun {describe⎇, Args {@i[object]⎇]
@f[describe] prints, to the stream in the variable @Varref[standard-output],
information about the @i[object].  Sometimes
it will describe something that it finds inside something else;
such recursive descriptions are indented appropriately.  For instance,
@f[describe] of a symbol will exhibit the symbol's value,
its definition, and each of its properties.  @f[describe] of a
floating-point number will exhibit its internal representation in a way
that is useful for tracking down round-off errors and the like.
The nature and format of the output is implementation-dependent.

@f[describe] returns no values (that is, it returns what the expression
@f[(values)] returns: zero values).
@Enddefun

@Defun[Fun {inspect⎇, Args {@i[object]⎇]
@f[inspect] is an interactive version of @f[describe].
The nature of the interaction is implementation-dependent,
but the purpose of @f[inspect] is to make it easy to wander
through a data structure, examining and modifying parts of it.
Implementations are encouraged to respond to the typing
of the character @f[?] by providing help, including a list
of commands.
@Enddefun

@Defun[Fun {room⎇, Args {@optional @i[x]⎇]
@f[room] prints, to the stream in the variable @Varref[standard-output],
information about the state of internal storage and its management.  This
might include descriptions of the amount of memory in use and the degree
of memory compaction, possibly broken down by internal data type if that
is appropriate.  The nature and format of the printed information is
implementation-dependent.  The intent is to provide information that may
help a user to tune his program to a particular implementation.

@f[(room nil)] prints out a minimal amount of information.
@f[(room t)] prints out a maximal amount of information.
Simply @f[(room)] prints out an intermediate amount
of information that is likely to be useful.
@Enddefun


@Defun[Fun {ed⎇, Args {@optional @i[x]⎇]
If the implementation provides a resident editor, this function
should invoke it.

@f[(ed)] or @f[(ed nil)] simply enters the editor, leaving you in the same
state as the last time you were in the editor.

@f[(ed @i[pathname])] edits the contents of the file specified
by @i[pathname].  The @i[pathname] may be an actual pathname
or a string.

@f[(ed @i[symbol])] tries to let you edit the text for the function
named @i[symbol].  The means by which the function text is obtained
is implementation-dependent; it might involve searching the file system,
or pretty-printing resident interpreted code, for example.
@Enddefun


@Defun[Fun {dribble⎇, Args {@optional @i[pathname]⎇]
@f[(dribble @i[pathname])] rebinds @Varref[standard-input]
and @Varref[standard-output], and/or takes other appropriate
action, so as to send a record of the
input/output interaction to a file named by @i[pathname].
The primary purpose of this is to create a readable record of an interactive
session.

@f[(dribble)] terminates the recording of input and output and
closes the dribble file.
@Enddefun


@Defun[Fun {apropos⎇, Args {@i[string] @optional @i[package]⎇]
@Defun1[Fun {apropos-list⎇, Args {@i[string] @optional @i[package]⎇]
@f[(apropos @i[string])] tries to find all available symbols whose print names
contain @i[string] as a substring.  (A symbol may be supplied for
the @i[string], in which case the print name of the symbol is used.)
Whenever @f[apropos] finds a symbol, it prints
out the symbol's name; in addition,
information about the function definition and dynamic value of the symbol,
if any, is printed.
If @i[package] is specified and not @nil, then only symbols
available in that package are examined;
otherwise ``all'' packages are searched, as if by @Macref[do-all-symbols].
Because a symbol may be available by way of more than one inheritance
path, @f[apropos] may print information about the same symbol more than once.
The information is printed to the stream that is the value
of @Varref[standard-output].
@f[apropos] returns no values (that is, it returns what the expression
@f[(values)] returns: zero values).

@f[apropos-list] performs the same search that @f[apropos] does, but
prints nothing.  It returns a list of the symbols whose print names
contain @i[string] as a substring.
@Enddefun

@Section[Environment Inquiries]

Environment inquiry functions provide information about the
environment in which a @clisp program is being executed.
They are described here in two categories: first, those dealing with
determination and measurement of time, and second, all the others,
most of which deal with identification of the computer hardware
and software.

@Subsection[Time Functions]
@Label[TIME-SECTION]

Time is represented in three different ways in @clisp:
Decoded Time, Universal Time, and Internal Time.
The first two representations
are used primarily to represent calendar time, and are
precise only to one second.
Internal Time is used primarily to represent measurements of computer
time (such as run time) and is precise to some implementation-dependent
fraction of a second, as specified by @Conref[internal-time-units-per-second].
Decoded Time format is used only for absolute time indications.
Universal Time and Internal Time formats are used for both absolute
and relative times.

Decoded Time format represents calendar time as a number of components:
@Begin[Itemize]
@i[Second]: an integer between 0 and 59, inclusive.

@i[Minute]: an integer between 0 and 59, inclusive.

@i[Hour]: an integer between 0 and 23, inclusive.

@i[Date]: an integer between 1 and 31, inclusive (the upper limit actually
depends on the month and year, of course).

@i[Month]: an integer between 1 and 12, inclusive; 1 means January,
12 means December.

@Begin[Multiple]
@i[Year]: an integer indicating the year A.D.  However, if this integer
is between 0 and 99, the ``obvious'' year is used; more precisely,
that year is assumed that is equal to the integer modulo 100 and
within fifty years of the current year (inclusive backwards
and exclusive forwards).  Thus, in the year 1978, year 28 is 1928
but year 27 is 2027.  (Functions that return time in this format always return
a full year number.)
@Incompatibility{This is incompatible with the @lmlisp definition
in two ways.  First, in @lmlisp a year between 0 and 99 always has 1900
added to it.  Second, in @lmlisp time functions return the abbreviated
year number between 0 and 99 rather than the full year number.  The
incompatibility is prompted by the imminent arrival of the twenty-first
century.  Note that @f[(mod @i[year] 100)] always reliably converts a
year number to the abbreviated form, while the inverse conversion can be
very difficult.⎇
@End[Multiple]

@Begin[Multiple]
@i[Day-of-week]: an integer between 0 and 6, inclusive;
0 means Monday, 1 means Tuesday, and so on; 6 means Sunday.
@End[Multiple]

@i[Daylight-saving-time-p]: a flag that, if not @false, indicates that
daylight saving time is in effect.

@i[Time-zone]: an integer specified as the number of hours west of @c[GMT]
(Greenwich Mean Time).  For example, in Massachusetts the time zone is 5,
and in California it is 8.  Any adjustment for daylight saving time is
separate from this.
@End[Itemize]

Universal Time represents time as a single non-negative integer.
For relative time
purposes, this is a number of seconds.  For absolute time, this is the
number of seconds since midnight, January 1, 1900 @c[GMT].  Thus the time 1
is 00:00:01 (that is, 12:00:01 @c[a.m.]) on January 1, 1900 @c[GMT].
Similarly, the time 2398291201 corresponds to time 00:00:01 on January 1,
1976 @c[GMT].
Recall that the year 1900 was @i[not] a leap year; for the purposes of
@clisp, a year is a leap year if and only if its number is divisible by 4, except
that years divisible by 100 are @i[not] leap years, except that years
divisible by 400 @i[are] leap years.  Therefore the year 2000 will
be a leap year.
(Note that the ``leap seconds'' that
are sporadically inserted by the world's official timekeepers as an additional
correction are ignored; @clisp assumes that every day is exactly 86400
seconds long.)
Universal Time format is used as a standard time
representation within the @c[ARPANET]; see reference @Cite[KLH-TIME-SERVER].
Because the @clisp Universal Time representation uses only
non-negative integers, times before the base time of midnight,
January 1, 1900 @c[GMT] cannot be processed by @clisp.

Internal Time also represents time as a single integer,
in terms of an implementation-dependent unit.
Relative time is measured as a number of these units.
Absolute time is relative to an arbitrary time base, typically
the time at which the system began running.

@Defun[Fun {get-decoded-time⎇, Args {⎇]
The current time is returned in Decoded Time format.  Nine values
are returned: @i[second], @i[minute], @i[hour], @i[date], @i[month],
@i[year], @i[day-of-week], @i[daylight-saving-time-p], and @i[time-zone].
@Incompatibility{In @lmlisp the @i[time-zone] is not currently returned.
Consider, however, the use of @clisp in some mobile vehicle.
It is entirely plausible that the time zone might change from time to time.⎇
@Enddefun

@Defun[Fun {get-universal-time⎇, Args {⎇]
The current time of day is returned as a single integer
in Universal Time format.
@Enddefun

@Defun[Fun {decode-universal-time⎇, Args {@i[universal-time] @optional @i[time-zone]⎇]
The time specified by @i[universal-time] in Universal Time format
is converted to Decoded Time format.  Nine values
are returned: @i[second], @i[minute], @i[hour], @i[date], @i[month],
@i[year], @i[day-of-week], @i[daylight-saving-time-p], and @i[time-zone].
@Incompatibility{In @lmlisp the @i[time-zone] is not currently returned.
Consider, however, the use of @clisp in some mobile vehicle.
It is entirely plausible that the time-zone might change from time to time.⎇
The @i[time-zone] argument defaults to the current time zone.
@Enddefun

@Defun[Fun {encode-universal-time⎇, Args {@i[second] @i[minute] @i[hour] @i[date] @i[month] @i[year] @optional @i[time-zone]⎇]
The time specified by the given components of Decoded Time format is
encoded into Universal Time format and returned.  If you don't specify
@i[time-zone], it defaults to the current time zone adjusted for daylight
saving time.  If you provide @i[time-zone] explicitly, no adjustment for
daylight saving time is performed.
@Enddefun

@Defcon[Var {internal-time-units-per-second⎇]
This value is an integer, the implementation-dependent
number of internal time units in a second.  (The internal time unit must
be chosen so that one second is an integral multiple of it.)
@Rationale{The reason for allowing the internal time
units to be implementation-dependent is so that
@Funref[get-internal-run-time] and @Funref[get-internal-real-time]
can execute with minimum overhead.
The idea is that it should be very likely that a fixnum will suffice as the
returned value from these functions.  This probability can be
tuned to the implementation by trading off the speed of the machine
against the word size.  Any particular unit will
be inappropriate for some implementations: a microsecond is too long
for a very fast machine, while a much smaller unit would
force many implementations to return bignums for most calls
to @f[get-internal-time], rendering that function less useful for accurate
timing measurements.⎇
@Enddefcon

@Defun[Fun {get-internal-run-time⎇, Args {⎇]
The current run time is returned as a single integer in Internal Time
format.
The precise meaning of this quantity is implementation-dependent;
it may measure real time, run time, CPU cycles, or some other quantity.
The intent is that the difference between the values of two calls
to this function be the amount of time between the two calls
during which the computational effort was expended on behalf of the
executing program.
@Enddefun

@Defun[Fun {get-internal-real-time⎇, Args {⎇]
The current time is returned as a single integer in Internal Time
format.  This time is relative to an arbitrary time base,
but the difference between the values of two calls
to this function will be the amount of elapsed real time between the two calls,
measured in the units defined by @Conref[internal-time-units-per-second].
@Enddefun

@Defun[Fun {sleep⎇, Args {@i[seconds]⎇]
@f[(sleep @i[n])] causes execution to cease and become dormant for
approximately @i[n] seconds of real time, whereupon execution is resumed.
The argument may be any non-negative non-complex number.
@f[sleep] returns @nil.
@Enddefun

@subsection[Other Environment Inquiries]

For any of the following functions, if no appropriate
and relevant result can be produced, @nil is returned instead
of a string.
@rationale{These inquiry facilities are functions rather than variables
against the possibility that a @clisp process might migrate from
machine to machine.  This need not happen in a distributed
environment; consider, for example, dumping a core image file
containing a compiler and then shipping it to another site.⎇

@Defun[Fun {lisp-implementation-type⎇, Args {⎇]
A string is returned that identifies the generic name of
the particular @clisp implementation.
Examples: @f["Spice LISP"], @f["Zetalisp"].
@Enddefun

@Defun[Fun {lisp-implementation-version⎇, Args {⎇]
A string is returned that identifies the version of
the particular @clisp implementation; this information
should be of use to maintainers of the implementation.
Examples: @f["1192"], @f["53.7 with complex numbers"],
@f["1746.9A, NEWIO 53, ETHER 5.3"].
@Enddefun

@Defun[Fun {machine-type⎇, Args {⎇]
A string is returned that identifies the generic name of
the computer hardware on which @clisp is running.
Examples: @f["DEC PDP-10"], @f["DEC VAX-11/780"].
@Enddefun

@Defun[Fun {machine-version⎇, Args {⎇]
A string is returned that identifies the version of
the computer hardware on which @clisp is running.
Example: @f["KL10, microcode 9"].
@Enddefun

@Defun[Fun {machine-instance⎇, Args {⎇]
A string is returned that identifies the particular
instance of the computer hardware on which @clisp is running;
this might be a local nickname, for example, and/or a serial number.
Examples: @f["MIT-MC"], @f["CMU GP-VAX"].
@Enddefun

@Defun[Fun {software-type⎇, Args {⎇]
A string is returned that identifies the generic name of
any relevant supporting software.
Examples: @f["Spice"], @f["TOPS-20"], @f["ITS"].
@Enddefun

@Defun[Fun {software-version⎇, Args {⎇]
A string is returned that identifies the version of
any relevant supporting software; this information
should be of use to maintainers of the implementation.
@Enddefun

@Defun[Fun {short-site-name⎇, Args {⎇]
@Defun1[Fun {long-site-name⎇, Args {⎇]
A string is returned that identifies the physical location
of the computer hardware.
Examples of short names: @f["MIT AI Lab"], @f["CMU-CSD"].
Examples of long names:
@Lisp
"MIT Artificial Intelligence Laboratory"
"Massachusetts Institute of Technology
Artificial Intelligence Laboratory"
"Carnegie-Mellon University Computer Science Department"
@Endlisp
@Enddefun

@nopara
See also @Funref[user-homedir-pathname].


@Defvar[Var {features⎇]
The value of the variable @var[features] should be a list of symbols
that name ``features'' provided by the implementation.
Most such names will be implementation-specific; typically
a name for the implementation will be included.
One standard feature name is @f[ieee-floating-point], which should
be present if and only if full @c[ieee] proposed floating-point
arithmetic @cite[IEEE-PROPOSED-FLOATING-POINT-STANDARD] is supported.

The value of this variable is used by the @f[#+] and @f[#-]
reader syntax.
@Enddefvar


@Section[Identity Function]

This function is occasionally useful as an argument to
other functions that require functions as arguments.  (Got that?)

@Defun[Fun {identity⎇, Args {@i[object]⎇]
The @i[object] is returned as the value of @f[identity].
@Enddefun